Summary

Resolves the long-standing "AI-assisted spec merge mode" open question (CLAUDE.md #4 historically). Re-running new / tech / tasks against an existing spec would overwrite PM edits — both `--force` (overwrite) and cancel are blunt. `refine` is the alternative.

Different shape from `clarify`:

• `clarify` finds gaps in a spec and walks the PM through them; the PM provides answers and the agent rewrites.
• `refine` takes the existing spec as ground truth for what the PM wants and re-grounds the parts that need it. No questions asked.

What it does

`draftwise refine [] [--type=product|tech|tasks]` reads the chosen file plus its source-of-truth and prints a three-phase agent instruction:

1. Audit — walk the spec section by section, decide strong (specific, grounded, well-worded → leave alone) or weak (vague, generic, ungrounded, contradictory → rewrite).
2. Re-ground — for each weak section, re-ground against the source-of-truth (scanner output for product/tech brownfield, overview.md for greenfield, plus the upstream spec for tech/tasks). Mark (unverified) or remove any code reference the scanner doesn't surface.
3. Write back — save to the same path. Preserve strong sections character-for-character and any YAML frontmatter at the top of `product-spec.md`.

Hard rules in the prompt:

• No fabricated code references.
• No scope creep — refine ≠ adding new features / edge cases. Genuine gaps go under "Open questions."
• Don't rewrite a section just because you'd word it differently. Bar is "actively misleads or under-specifies," not "could be tighter."
• Don't touch sections you'd classify as strong; if the whole spec is already strong, exit without writing.

Type-aware behavior

Same auto-pick / multi-spec / unknown-slug ergonomics as `tech`.

What changed

• New prompt `src/ai/prompts/refine.js` — `buildAgentInstruction(slug, type, projectState)` with a per-type metadata table at the top (file name, source-of-truth labels, section-preservation rule).
• New command `src/commands/refine.js` — parses `--type`, branches on it for filter / upstream / scanner-vs-overview / heading labels.
• Routed via `COMMANDS` in `src/index.js`; help block lists `refine []`.
• 16 new tests in `test/commands/refine.test.js` covering: missing `.draftwise/`, no specs, unknown `--type`, parseArgs strict, auto-pick / slug / multi-spec / unknown-slug for product, `--type=tech` upstream + scanner, `--type=tasks` upstream + no-scanner, greenfield product, missing-upstream errors for tech and tasks, no-disk-write, three-phase + no-fabrication + no-scope-creep instruction text.
• CHANGELOG `[Unreleased] ### Added` entry; CLAUDE.md (commands list, v1 status Implement draftwise tech [<feature>] #7, new "Refine, don't clobber" design principle); README commands table.

Test plan

• `npm test` — 257 passing
• `npm run lint` — clean
• Smoke: in a repo with one product spec, `draftwise refine` auto-picks; `draftwise refine alpha --type=tech` errors when product-spec missing; `--type=summary` errors with the expected list.